.TH "frovedis::sliced_colmajor_vector_local<T>" "" "" "" ""
.SH NAME
.PP
\f[C]frovedis::sliced_colmajor_vector_local<T>\f[] \- a data structure
containing the row or column wise slicing information of a
two\-dimensional \f[C]frovedis::colmajor_matrix_local<T>\f[]
.SH SYNOPSIS
.PP
\f[C]#include\ <frovedis/matrix/sliced_vector.hpp>\f[]
.SS Constructors
.PP
sliced_colmajor_vector_local ()
.PD 0
.P
.PD
sliced_colmajor_vector_local (const \f[C]colmajor_matrix_local<T>\f[]&
m)
.PD 0
.P
.PD
sliced_colmajor_vector_local (const \f[C]std::vector<T>\f[]& v)
.SS Public Member Functions
.PP
bool is_valid () const
.PD 0
.P
.PD
void debug_print () const
.SS Public Data Members
.PP
T* data
.PD 0
.P
.PD
size_t size
.PD 0
.P
.PD
size_t stride
.SH DESCRIPTION
.PP
In order to perform vector operations on some rows or on some columns of
a dense matrix, frovedis provides some sliced data structures.
\f[C]sliced_colmajor_vector_local<T>\f[] is one of them.
It is actually not a real vector, rather it only contains some slicing
information of a physical \f[C]colmajor_matrix_local<T>\f[].
Thus any changes performed on the sliced vector, would actually make
changes on the specific row or column of the physical matrix from which
the slice was made.
.PP
Like \f[C]colmajor_matrix_local<T>\f[], a
\f[C]sliced_colmajor_vector_local<T>\f[] is also a template based
structure with type \f[B]"T"\f[].
This has the below structure:
.IP
.nf
\f[C]
template\ <class\ T>
struct\ sliced_colmajor_vector_local\ {
\ \ T*\ data;\ \ \ \ \ \ \ \ //\ pointer\ pointing\ to\ the\ begining\ of\ the\ row\ or\ column\ to\ be\ sliced
\ \ size_t\ size;\ \ \ \ //\ number\ of\ elements\ in\ the\ sliced\ vector
\ \ size_t\ stride;\ \ //\ stride\ between\ two\ consecutive\ elements\ in\ the\ sliced\ vector
};
\f[]
.fi
.PP
E.g., if a physical \f[C]colmajor_matrix_local<T>\f[] M has dimensions
4x4 and its 2nd row needs to be sliced, then
.PD 0
.P
.PD
"data" will hold the address of M[0][1] (not M[1][0], since matrix is
stored in colmajor order),
.PD 0
.P
.PD
"size" would be 4 (number of elements in 2nd row),
.PD 0
.P
.PD
and "stride" would be 4 (since matrix is stored in colmajor order, the
stride between two consecutive elements in a row would be equal to
leading dimension of that matrix, i.e., number of rows in that matrix).
.PP
On the other hand, if 2nd column needs to be sliced, then
.PD 0
.P
.PD
"data" will hold the address of M[1][0] (not M[0][1], since matrix is
stored in colmajor order),
.PD 0
.P
.PD
"size" would be 4 (number of elements in 2nd column),
.PD 0
.P
.PD
and "stride" would be 1 (since matrix is stored in colmajor order, the
consecutive elements in a column would be placed one after another).
.PP
Such vectors are very useful in operations of external libraries like
blas etc.
.SS Constructor Documentation
.SS sliced_colmajor_vector_local ()
.PP
This is the default constructor which creates an empty sliced vector
with size = stride = 0 and "data" points to NULL.
In general of no use, unless it is needed to manipulate the slice
information explicitly.
.SS sliced_colmajor_vector_local (const
\f[C]colmajor_matrix_local<T>\f[]& m)
.PP
This is a special constructor for implicit conversion.
This constructor treats an entire physical matrix as a sliced vector.
Thus the created \f[C]sliced_colmajor_vector_local<T>\f[] would have
"size" equals to number of rows in the input
\f[C]colmajor_matrix_local<T>\f[], "stride" equals to 1 and "data"
pointing to the base address of the input
\f[C]colmajor_matrix_local<T>\f[].
Please note that such conversion can only be posible if the input matrix
can be treated as a column vector (a matrix with multiple rows and
single column), else it throws an exception.
.SS sliced_colmajor_vector_local (const \f[C]std::vector<T>\f[]& v)
.PP
This is a special constructor for implicit conversion.
This constructor treats an entire physical vector as a sliced vector.
Thus the created \f[C]sliced_colmajor_vector_local<T>\f[] would have
"size" equals to the length of the input \f[C]std::vector<T>\f[],
"stride" equals to 1 and "data" pointing to the base address of the
input vector.
.SS Public Member Function Documentation
.SS bool is_valid () const
.PP
This function returns true, if the caller object is a valid sliced
vector, else it returns false.
.PD 0
.P
.PD
Kindly note that an empty sliced vector is also an invalid sliced
vector, since no valid operation can be performed on its data pointing
to NULL.
.SS void debug_print () const
.PP
It prints the contents of the sliced row or column of the original
(physical) \f[C]colmajor_matrix_local<T>\f[] on the user standard output
terminal.
.SS Public Data Member Documentation
.SS data
.PP
A pointer of type "T" pointing to the beginning of the row or column of
a physical \f[C]colmajor_matrix_local<T>\f[] from which slice has been
made.
.SS size
.PP
A size_t attribute to contain the number of elements in the sliced
vector.
.SS stride
.PP
A size_t attribute to contain the stride between two consecutive
elements in a sliced vector.
.SS Public Global Function Documentation
.SS make_row_vector (mat, row_index)
.PP
\f[B]Parameters\f[]
.PD 0
.P
.PD
\f[I]mat\f[]: An object of either \f[C]colmajor_matrix_local<T>\f[] or
\f[C]sliced_colmajor_matrix_local<T>\f[] type.
.PD 0
.P
.PD
\f[I]row_index\f[]: A size_t attribute to indicate the row index to be
sliced.
.PP
\f[B]Purpose\f[]
.PD 0
.P
.PD
This function accepts a valid \f[C]colmajor_matrix_local<T>\f[] or
\f[C]sliced_colmajor_matrix_local<T>\f[] with the row index to be sliced
(index starts with 0).
On receiving valid inputs, it outputs a
\f[C]sliced_colmajor_vector_local<T>\f[] object containing the slicing
information, else it throws an exception.
.PP
\f[B]Example\f[]:
.PD 0
.P
.PD
If a physical \f[C]colmajor_matrix_local<T>\f[] "mat" has the dimensions
4x4 and its 2nd row needs to be sliced, then this function should be
called like:
.IP
.nf
\f[C]
auto\ rvec\ =\ make_row_vector(mat,1);\ //\ row\ index\ of\ second\ row\ is\ 1\ \ \ 

Input\ (mat):\ \ \ \ \ \ \ \ Output\ (rvec):
\-\-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\-\-\-\-
1\ 2\ 3\ 4\ \ \ \ \ \ \ =>\ \ \ \ 5\ 6\ 7\ 8
5\ 6\ 7\ 8\ \ \ \ \ \ \ \ \ \ \ 
8\ 7\ 6\ 5\ \ \ \ \ \ \ \ \ \ \ \ \ 
4\ 3\ 2\ 1
\f[]
.fi
.PP
Now if it is needed to slice the 2nd row from its 4th block
(sub\-matrix), then the operations can be performed as per the code
below:
.IP
.nf
\f[C]
auto\ smat\ \ \ =\ make_sliced_colmajor_matrix_local(mat,2,2,2,2);
auto\ s_rvec\ =\ make_row_vector(smat,1);
\f[]
.fi
.PP
First the original matrix needs to be sliced to get its 4th block (3rd
row and 3rd column till 4th row and 4th column) and then 2nd row is to
be sliced from the sub\-matrix.
.PP
Kindly note that 2nd row of "smat" is actually the 4th row of the
physical matrix "mat", but this function takes care of it internally.
Thus user only needs to take care of the index of the input sliced
matrix, not the actual physical matrix.
.IP
.nf
\f[C]
Input\ (mat):\ \ \ \ \ \ \ Output\ (smat):\ \ \ \ \ \ Output\ (s_rvec):
\-\-\-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1\ 2\ 3\ 4\ \ \ \ \ \ \ \ \ \ \ \ 6\ 5\ \ \ \ \ \ \ \ \ \ \ \ \ =>\ \ 2\ 1
5\ 6\ 7\ 8\ \ \ \ \ \ \ =>\ \ \ 2\ 1
8\ 7\ 6\ 5\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 
4\ 3\ 2\ 1
\f[]
.fi
.PP
\f[B]Return Value\f[]
.PD 0
.P
.PD
On success, this function returns the sliced row vector of the type
\f[C]sliced_colmajor_vector_local<T>\f[].
Otherwise it throws an exception.
.SS make_col_vector (mat, col_index)
.PP
\f[B]Parameters\f[]
.PD 0
.P
.PD
\f[I]mat\f[]: An object of either \f[C]colmajor_matrix_local<T>\f[] or
\f[C]sliced_colmajor_matrix_local<T>\f[] type.
.PD 0
.P
.PD
\f[I]col_index\f[]: A size_t attribute to indicate the column index
needs to be sliced.
.PP
\f[B]Purpose\f[]
.PD 0
.P
.PD
This function accepts a valid \f[C]colmajor_matrix_local<T>\f[] or
\f[C]sliced_colmajor_matrix_local<T>\f[] with the column index to be
sliced (index starts with 0).
On receiving the valid inputs, it outputs a
\f[C]sliced_colmajor_vector_local<T>\f[] object containing the slicing
information, else it throws an exception.
.PP
\f[B]Example\f[]:
.PD 0
.P
.PD
If a physical \f[C]colmajor_matrix_local<T>\f[] "mat" has the dimensions
4x4 and its 2nd column needs to be sliced, then this function should be
called like:
.IP
.nf
\f[C]
auto\ cvec\ =\ make_col_vector(mat,1);\ //\ column\ index\ of\ second\ column\ is\ 1

Input\ (mat):\ \ \ \ \ \ \ \ Output\ (cvec):
\-\-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\-\-\-\-
1\ 2\ 3\ 4\ \ \ \ \ \ \ =>\ \ \ \ 2\ 6\ 7\ 3
5\ 6\ 7\ 8
8\ 7\ 6\ 5
4\ 3\ 2\ 1
\f[]
.fi
.PP
Now if it is needed to slice the 2nd column from its 4th block
(sub\-matrix), then the operations can be performed as per the code
below:
.IP
.nf
\f[C]
auto\ smat\ \ \ =\ make_sliced_colmajor_matrix_local(mat,2,2,2,2);
auto\ s_cvec\ =\ make_col_vector(smat,1);
\f[]
.fi
.PP
First the original matrix needs to be sliced to get its 4th block (3rd
row and 3rd column till 4th row and 4th column) and then 2nd column is
to be sliced from the sub\-matrix.
.PP
Kindly note that 2nd column of "smat" is actually the 4th column of the
physical matrix "mat", but this function takes care of it internally.
Thus user only needs to take care of the index of the input sliced
matrix, not the actual physical matrix.
.IP
.nf
\f[C]
Input\ (mat):\ \ \ \ \ \ \ Output\ (smat):\ \ \ \ \ \ Output\ (s_cvec):
\-\-\-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1\ 2\ 3\ 4\ \ \ \ \ \ \ \ \ \ \ \ 6\ 5\ \ \ \ \ \ \ \ \ \ \ \ \ =>\ \ 5\ 1
5\ 6\ 7\ 8\ \ \ \ \ \ \ =>\ \ \ 2\ 1
8\ 7\ 6\ 5
4\ 3\ 2\ 1
\f[]
.fi
.PP
\f[B]Return Value\f[]
.PD 0
.P
.PD
On success, it returns the sliced column vector of the type
\f[C]sliced_colmajor_vector_local<T>\f[].
Otherwise it throws an exception.
.SH SEE ALSO
.PP
colmajor_matrix, sliced_colmajor_matrix_local
